// 引入 y-protocols 中的 awareness 协议模块，主要用于管理协同编辑中的用户状态（如光标位置、用户名等）
import * as awarenessProtocol from 'y-protocols/awareness.js';
import * as Y from 'yjs';

/**
 * 扩展 Yjs 的共享文档（Y.Doc）接口，添加用于 WebSocket 协同的额外字段
 */
export interface IWSSharedDoc extends Y.Doc {
	// 文档名称（用于标识不同的共享文档）
	name: string;

	// 当前文档中所有连接的客户端
	// key：表示某个连接对象（可以是 WebSocket 对象等）
	// value：该连接对象订阅的客户端 ID 集合（Set<number>）
	conns: Map<Object, Set<number>>;

	// 文档级别的 awareness 实例，用于同步客户端的状态（如用户光标、用户名等）
	awareness: awarenessProtocol.Awareness;
}

/**
 * 持久化适配器接口，用于将 Yjs 文档的状态持久化到后端数据库（如 PostgreSQL）
 */
export interface IPersistence {
	/**
	 * 在文档首次连接时绑定持久化状态
	 * @param arg1 文档名称
	 * @param arg2 当前共享文档实例（包含 Y.Doc、awareness 等）
	 */
	bindState: (arg1: string, arg2: IWSSharedDoc) => void;

	/**
	 * 在所有连接关闭或服务器主动保存时，写入持久化状态
	 * @param arg1 文档名称
	 * @param arg2 当前共享文档实例
	 * @returns Promise 用于等待持久化完成
	 */
	writeState: (arg1: string, arg2: IWSSharedDoc) => Promise<any>;

	/**
	 * 可选字段：持久化提供者的实例（用于支持更多操作）
	 */
	provider?: any;
}
